Excel 数据交换 · Excel IO
在 Grasshopper 与 Excel 之间双向交换数据，支持模板复制与树形结构写入
📖 功能概述
ExcelIO 是 LK 工具集中最核心的数据交换组件，基于 EPPlus 5.3.1 库实现，支持在 Grasshopper 和 Excel 之间进行高效、可靠的读写操作。
- 写入模式：将树形结构数据（每行一个逗号分隔字符串）写入 Excel，每个数据分支对应一个独立文件
- 读取模式：从 Excel 文件中读取指定工作表，输出逗号分隔的数据列表
- 右键一键切换读写模式，参数面板动态变化
- 支持 模板文件——首次写入时自动拷贝模板到目标路径
- 自动识别数值类型（整数/浮点数），写入时保留类型信息
- 精确到单元格的位置控制，支持指定起始单元格
💡 状态提示：组件标题栏实时显示当前模式——写入时显示「写入Excel」，读取时显示「读取Excel」。
🔄 右键切换 — 读写模式转换
右键点击组件，弹出菜单中有一个切换项：
- 当前为写入模式 → 菜单显示「切换为读取模式」
- 当前为读取模式 → 菜单显示「切换为写入模式」
切换后组件会：
- 清空所有输入/输出参数
- 按新模式重新注册参数
- 更新组件的显示名称和描述
- 重新排版布局
- 触发重新求解
✅ 状态持久化：当前模式通过
Write / Read 序列化保存到 Grasshopper 文档中，下次打开自动恢复。
📥 输入参数（写入模式）
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 执行写入 (W) | Boolean | 可选 | 设为 True 或点击组件按钮执行写入操作。默认不触发。 |
| 文件路径 (P) | 必需 | 输出文件的完整路径列表。路径数量必须与数据分支数量完全一致，一个路径对应一个分支。 | |
| 模板路径 (T) | File Path | 可选 | Excel 模板文件路径。仅在目标文件不存在时生效——组件会先拷贝模板到输出路径再写入数据。如果模板路径无效或指向不存在的文件，组件会发出警告并直接创建新文件。 |
| 工作表 (S) | Text | 可选 | 目标工作表名称。默认 Sheet1。如果文件已存在且包含同名工作表则使用已有表，否则创建新表。 |
| 起始单元格 (C) | Text | 可选 | 数据写入的起始位置，如 A1、B5 等。默认 A1。 |
| 数据 (D) | Text Tree | 必需 | 要写入的树形结构数据。每行一个字符串，逗号分隔各列。树的每个分支对应一个 Excel 文件。 |
📤 输出参数（写入模式）
| 名称 | 类型 | 说明 |
|---|---|---|
| 无输出参数 | — | 写入模式下组件直接操作文件，不输出数据。执行结果通过消息区反馈。 |
📥 输入参数（读取模式）
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 执行读取 (R) | Boolean | 必需 | 设为 True 或点击按钮执行读取操作。默认 False。 |
| 文件路径 (P) | File Path | 必需 | 源 Excel 文件路径。支持包含引号的路径——组件自动去除首尾双引号。 |
| 工作表 (S) | Text | 可选 | 工作表名称或索引（从 1 开始）。默认 1（第一个工作表）。 |
| 单元格范围 (C) | Text | 可选 | 读取范围。输入 All 读取全部有效数据区域，或指定范围如 A1:B15。默认 All。 |
📤 输出参数（读取模式）
| 名称 | 类型 | 说明 |
|---|---|---|
| 数据 (D) | 读取的逗号分隔数据行列表。每行字符串对应 Excel 的一行数据。 |
🧠 核心机制
写入模式工作流
1. 验证与准备
检查触发条件（按钮或 W 输入），验证文件路径列表数量与数据分支数量是否匹配。若不匹配，报错并终止。
2. 模板处理
如果目标文件不存在且提供了有效的模板路径，先复制模板到目标位置，再打开进行写入。如果模板路径无效（文件不存在），发出 Warning 但继续——直接创建新文件。
✅ 目录自动创建：如果目标目录不存在，组件会自动创建，无需手动建文件夹。
3. 工作表处理
根据目标文件打开 ExcelPackage，检查是否已存在同名工作表：
- 存在 → 使用已有工作表（保留已有内容，覆盖指定区域）
- 不存在 → 创建新工作表，工作表索引自动递增
4. 智能类型写入
解析每个单元格的字符串值：
| 输入字符串 | 写入类型 | Excel 效果 |
|---|---|---|
"123" | int | 数字格式，右对齐 |
"3.14" | double | 浮点数格式 |
"ABC-01" | string | 文本格式，左对齐 |
""（空） | string.Empty | 空单元格 |
数值识别使用 CultureInfo.InvariantCulture，确保小数点处理不受系统区域设置影响。
5. 批量写入
所有数据转换为 object[,] 二维数组后，通过 worksheet.Cells.Value 一次赋入——这是 EPPlus 中最高效的写入方式。
6. 保存
调用 package.Save() 写入磁盘。EPPlus 会在 using 块结束时自动管理文件流。
读取模式工作流
1. 文件验证
检查文件是否存在。如果路径带引号（如从某些文本组件输出），自动去除首尾双引号。
2. 工作表定位
通过 GetWorksheet 方法定位工作表：
- 先按名称查找（不区分大小写）
- 若没找到，尝试按数字索引解析（
1= 第一个表） - 若两者都无效，返回第一个工作表作为兜底
3. 智能范围识别
ProcessRangeDefinition 方法处理用户指定的范围：
- All——自动检测有效数据范围，跳过空行/空列，返回精简的矩形区域
- 自定义范围（如
A1:D20）——按指定范围读取
自动检测范围时，GetExactDataRange 方法从四边扫描空行/空列，精确裁剪到实际数据区域。
4. 数据转换
将 object[,] 二维数组的每行拼接为逗号分隔的字符串，输出到 Grasshopper。
🧪 典型使用场景
| 场景 | 说明 |
|---|---|
| 装配表导出 | 将 AssemblyAttributes 生成的 CSV 装配表写入 Excel，配合模板文件保持列宽、表头格式等预设样式。 |
| 参数化明细表 | 数据树中每个分支对应一个板块的零件清单，分支写入不同的 Excel 文件，实现一键批量出表。 |
| 读取配置数据 | 从 Excel 配置表中读取参数数据（如截面规格、材料属性），切换为读取模式后接入 ExcelPath 生成的路径。 |
| 模板化报表 | 使用含格式的 Excel 模板文件，组件将数据填入指定起始单元格，保留模板的列宽、合并单元格、字体等格式。 |
⚠️ 注意事项
- EPPlus 许可证：组件使用
NonCommercial许可证模式，适用于非商业用途。商业使用需要 EPPlus 商业授权。 - 写入模式下的路径-分支对应：文件路径列表的数量必须严格等于数据树的分支数量。常用做法是使用
ExcelPath生成路径，路径数量自动匹配。 - 模板文件只拷贝一次：模板复制仅在目标文件不存在时发生。如果目标文件已存在，模板参数不生效。
- 读写模式参数不同：切换模式后参数会完全重排——如果连线模式不匹配，Grasshopper 会报告连接错误。右击切换后需要重新连接参数。
- 读取路径去引号：如文件路径前后带双引号（常见于某些字符串组件的输出），组件会自动去除。
- 数据覆盖区域：写入时覆盖指定起始单元格区域中的数据，不会清除区域外已有内容。如需完全替换，建议使用新工作表或预先清空。
- 组件不依赖 Excel 安装，基于 EPPlus 库直接操作
.xlsx文件——不需要机器上安装 Microsoft Office。 - 源文件名为
ExcelIO.cs，类名为ExcelIO。
📋 组件信息
| 名称 | Excel 数据交换 |
| 英文名 | Excel IO |
| 分类 | LK → File Management |
| 按钮文字 | Action |
| 基类 | BoolButtonComponent（动态参数） |
| GUID | {5A155500-884B-4BF3-A2B7-9D2C274DC664} |